|
Login |
| http://www.borland.com/ |
| |||||||||||||||||||||||
|
AppServer | |
C# | |
C++ | |
CORBA | |
CaliberRM | |
Delphi | |
InterBase | |
JDataStore | |
Java | |
StarTeam | |
Together | |
|
Delphi and Microsoft HTML Help
Abstract: A paper that will guide you in creating HTML Help files and use them in your Delphi applications.
A white paper and tutorial by Vino Rodrigues
vinorodrigues@yahoo.com
www.geocities.com/vinorodrigues
What will be covered in this paper:
Microsoft® HTML Help is the standard help system for the Windows 98 and 2000 platforms. Authors can use HTML Help to create online help for a software application or to create content for a multimedia title or Web site. Developers can use the HTML Help API to program a host application or hook up context-sensitive help to an application. As an information delivery system, HTML Help is suited for a wide range of applications, including training guides, interactive books, and electronic newsletters, as well as help for software applications.
HTML Help offers some distinct advantages over standard HTML, such as the ability to implement a combined table of contents and index and the use of keywords for advanced hyperlinking capability. The HTML Help compiler (part of the HTML Help Workshop) makes it possible to compress HTML, graphic, and other files into a relatively small compiled help (.chm) file, which can then be distributed with a software application, or downloaded from the Web.
HTML Help consists of the following components:
Microsoft HTML Help is available and free to download from: http://msdn.microsoft.com/workshop/author/htmlhelp/
Delphi does not include an implementation of HTML Help, but one can easily be created. The process involves creating some API that call the HTMLHelp API and trapping Delphi application events to trigger the HTML Help system.
You can get the complete 'htmlhelp.h' object pascal translation form the web, but for this example will only use the following API:
const
HH_DISPLAY_TOPIC = $0000;
HH_DISPLAY_TOC = $0001;
HH_CLOSE_ALL = $0012;
function HtmlHelp(hwndCaller: HWND;
pszFile: PChar; uCommand: UINT;
dwData: DWORD): HWND; stdcall;
external 'HHCTRL.OCX' name 'HtmlHelpA';
We will discuss trapping help events in the example.
NOTE: You will need 'Microsoft HTML Help Workshop' to complete this paper and it is available and free to download from: http://msdn.microsoft.com/workshop/author/htmlhelp/
An HTML help project (.hhp) file is a text file that brings together all the elements of a help project. It contains the data HTML Help Workshop needs to combine topic (.html, .htm), image (.jpeg, .gif, .png), index (.hhk), and contents (.hhc) files into a single compiled help (.chm) file.
The project file also contains information about how a compiled help file will appear. Window definitions you create in the project file determine attributes of your help windows, such as size and position.
As a help author, you create the project file and add to it the locations of your topic, contents, index, and other files. You can modify the project file options and customize your help windows to match the design of your system. You can make other changes depending on the size and complexity of your help system.
When you create a new project, contents, or index file, the minimum necessary settings are added automatically. The project file is divided into sections; for example, [FILES] and [OPTIONS] are included in every help project file. You can edit these sections by double-clicking the section title.
Once your project file is complete, you compile it to create the final help file. Then you test the help file to make sure everything appears the way you want it.
The Microsoft HTML Help workshop comes with extensive documentation we do not want to reproduce here. (-- Yea! Right!)
You will need to start up the HTML Help Workshop.
The most important information that you provide in a project file is the location of your HTML topic, contents (.hhc), and index (.hhk) files. This enables HTML Help Workshop to find all the information it needs to compile a help file.
To add or remove HTML topic files from a project file
Note: When using HTML Help Workshop, the number of topic files you can view and add is limited to 5,000. Projects with more than 5,000 files will compile correctly, and links from entries in the index and contents files will work, but you will need to use a text editor to view, add, or edit them.
Note: If you want a contents file created for you, select the Automatically create contents file (.hhc) when compiling check box, and then in the Maximum heading level box, select the heading level at which you want contents entries to be created.
Note: You can also specify how the contents entries you create will respond when you single-click or double-click them in HTML Help Workshop.
Note: You can also specify how the index entries you create will respond when you single-click or double-click them in HTML Help Workshop.
If you are compiling your files, the HTML Help compiler will automatically add any referenced files to your project at compile time.
Note: The HTML Help Image Editor, a graphic editing tool that comes with HTML Help Workshop, makes it easy to take screen shots and add them to your help files.
The following text will teach you the process of creating a help file project from scratch:
<HTML>
<HEAD>
<TITLE>Welcome</TITLE>
</HEAD>
<BODY>
<H1>Hello World</H1>
This will be your default page.
</BODY>
</HTML>
(Afterward you should see the file listed in the '[Files]' group.)
Name the Entry title as "Sample Help" and then press the 'Add…' button and select the 'Welcome' page (default.htm). Then the 'OK' button.
Note: We can add more files to the Contents (by inserting headings
or pages). The files can be accessed in an hierarchy fashion (by using the
'Move selection up | down | left | right' buttons.
Remember that the help
file is a virtual web-site and that the files are most likely structured in a
flat fashion - but that does not stop you from creating a complex tree
contents, which is just links to the HTML files.
Once the 'Table of Contents Entry' dialog appears select the 'Advanced' tab and change the 'Image index' to "1". Press 'OK'.
function TForm1.HH(Command: Word; Data: Integer;
var CallHelp: Boolean): Boolean;
begin
if (Command = 0) and (Data = 0) then
HtmlHelp(Application.Handle,
PChar(Application.HelpFile),
HH_DISPLAY_TOC, 0);
CallHelp := False;
end;
Note: CallHelp must be set to FALSE to prevent Delphi from calling WinHelp.
Application.OnHelp := HH;¹ This step can be replaced by a TApplicationEvents object, and trapping it's 'OnHelp' event handler.
HH(0, 0, dummy);
This is a tricky one. The easiest way to implement a HelpContext (which in Delphi is an Integer) is to name the HTML files by HelpContext value:
i.e. If the HelpContext was 100 then the help HTML file would be named '100.htm'.
In the following example we formated the HTML file in the following fashion:
Hnnnnn.htm
(Where nnnnn is the zero padded HelpContext value.)
To access the a HelpContext specific file simply add the following code to the custom OnHelp event:
if (Command = 1) then
HtmlHelp(Application.Handle,
PChar(Format('%s::/H%5.5d.htm',
[Application.HelpFile, Data])),
HH_DISPLAY_TOPIC, 0);
Note: The Command value of "1" depicts that the F1 key was pressed.
HTML help provides a simple function to close all windows opened directly or indirectly by the calling program:
HtmlHelp(0, nil, HH_CLOSE_ALL, 0);Download some source code for this paper:
These files include:
Add or View comments on this article
NOTE: The views and information expressed in this document represent those of its author(s) who are solely responsible for its content. Borland does not make or give any representation or warranty with respect to such content.
Article ID: 27842 Publish Date: October 09, 2001 Last Modified: October 09, 2001